连接至数据库
在 Java™ 程序中通过以下两个步骤来建立至 GBase 8s 数据库服务器的连接：
- 加载 GBase 8s JDBC Driver。
- 以下列方式之一，来创建连接：
- 使用 DataSource 对象。
- 使用 DriverManager.getConnection() 方法。
使用 DataSource 对象比使用 DriverManager.getConnection() 方法更好，因为 DataSource 对象轻便，且使得关于隐含数据源的详细信息对应用程序是透明的。可修改目标数据源实现，或可将应用程序重定向至不同的服务器，而不影响应用程序代码。
DataSource 对象还可提供对连接池和分布式事务的支持。 此外，Enterprise JavaBeans™ 和 J2EE 需要 DataSource 对象。
下列附加的连接选项是可用的：
- 设置环境变量
- 动态地读取 GBase 8s sqlhosts 文件
- 使用 HTTP 代理服务器
- 使用口令加密
- 使用网络加密
加载 GBase 8s JDBC 驱动程序
要加载 GBase 8s JDBC Driver，请使用 Class.forName() 方法，将值 com.gbasedbt.jdbc.Driver 传给它：
try
{
Class.forName("com.gbasedbt.jdbc.Driver");
}
catch (Exception e)
{
System.out.println("ERROR: failed to load GBase 8s JDBC driver.");
e.printStackTrace();
return;
}
Class.forName() 方法加载 Driver 类 Driver 的 GBase 8s 实现。然后，Driver 创建驱动程序的实例，并以 DriverManager 类来注册它。
在已加载了 GBase 8s JDBC Driver 之后，准备好连接至 GBase 8s 数据库或数据库服务器。
如果您正在编写以 Microsoft™ Internet Explorer 来查看的 applet，则可能需要显式地注册 GBase 8s JDBC Driver，以避免平台不兼容。
要显式地注册驱动程序，请使用 DriverManager.registerDriver() 方法：
Class.forName("com.gbasedbt.jdbc.Driver").newInstance();
此方法可能注册 GBase 8s JDBC Driver 两次，这不会导致问题。
DataSource 对象
GBase 8s JDBC Driver 扩展标准 DataSource 接口，以允许在 DataSource 对象中定义连接属性（标准属性和 GBase 8s 环境变量），而不是通过 URL。
下表描述 GBase 8s 连接属性如何对应于 DataSource 属性。
| GBase 8s 连接属性 | DataSource 属性 | 数据类型 | 是否必需？ | 描述 |
|---|---|---|---|---|
| IFXHOST | 无；要了解如何设置请参阅DataSource 扩展。 | String | 对于客户机侧 JDBC，必需，除非定义SQLH_TYPE；对于服务器侧 JDBC, 不是必需的 | 运行 GBase 8s 数据库服务器的计算机的 IP 地址或主机名称 |
| PORTNO | portNumber | int | 对于客户机侧 JDBC，必需，除非定义SQLH_TYPE；对于服务器侧 JDBC, 不是必需的 | GBase 8s 数据库服务器的端口号。该端口号罗列在 /etc/services 文件中。 |
| DATABASE | databaseName | String | 不是必需的，除非连接来自运行在数据库服务器中的 web 应用程序（诸如浏览器） | 您想要连接至其的 GBase 8s 数据库的名称 如果未指定数据库的名称，则制作至GBase 8s 数据库服务器的连接。 |
| GBASEDBTSERVER | serverName | String | 对于客户机侧 JDBC，必需；对于服务器侧 JDBC，忽略 | 您想要连接至其的 GBase 8s 数据库服务器的名称 |
| USER | user | String | 必需 | 当连接至 GBase 8s 数据库或数据库服务器时，用户名称控制（或决定）会话权限 通常，必须同时指定用户名称和口令；然而，如果 DBMS 信任运行 JDBC 应用程序的用户，则可能都省略。 |
| PASSWORD | password | String | 必需 | 用户的口令 通常，必须同时指定用户名称和口令；然而，如果 DBMS 信任运行 JDBC 应用程序的用户，则可能都省略。 |
| 无 | description | String | 必需 | DataSource 对象的描述 |
| 无 | dataSourceName | String | 不是必需的 | 对于连接池或分布式事务，隐含的ConnectionPoolDataSource 或XADataSource 对象的名称 |
不受支持的连接属性
GBase 8s JDBC Driver 不支持 networkProtocol 和 roleName 属性。
指定连接信息
如果 LDAP（轻型目录访问协议）服务器或 sqlhosts 文件通过 SQLH_TYPE 属性提供 GBase 8s 数据库服务器的 IP 地址、主机名称或端口号或服务名称，则不必使用标准 DataSource 属性来指定它们。
ConnectionPoolDataSource 对象
要获取关于 ConnectionPoolDataSource 对象的信息，请参阅 连接池。
环境变量
要获取受支持的环境变量（属性）的列表，请参阅 随同 GBase 8s JDBC 驱动程序的 GBase 8s 环境变量。要获取 GBase 8s DataSource 扩展的列表，其允许您定义环境变量值和连接池调整参数，请参阅 DataSource 扩展。驱动程序不查询用户环境来确定环境变量值。
高可用性数据复制
可随同“高可用性数据复制”来使用 DataSource 对象。要获取更多信息，请参阅 连接至高可用性集群的服务器。
示例：在示例程序中使用 DataSource 对象
下列来自 pickaseat 示例程序的代码定义并使用 DataSource 对象：
IfxConnectionPoolDataSource cpds = null;
try
{
Context initCtx = new InitialContext();
cpds = new IfxConnectionPoolDataSource();
cpds.setDescription("Pick-A-Seat Connection pool");
cpds.setIfxIFXHOST("158.58.60.88");
cpds.setPortNumber(179);
cpds.setUser("demo");
cpds.setPassword("demo");
cpds.setServerName("ipickdemo_tcp");
cpds.setDatabaseName("ipickaseat");
cpds.setIfxGL_DATE("%B %d, %Y");
initCtx.bind("jdbc/pooling/PickASeat", cpds);
}
catch (Exception e)
{
System.out.println("Problem with registering the CPDS");
System.out.println("Error: " + e.toString());
}
示例：使用带有 IFX_LOCK_MODE_WAIT 连接属性的 DataSource 对象
下列是使用 DataSource 对象的 IFX_LOCK_MODE_WAIT 连接属性的示例：
示例 1
IfxDataSource ds = new IfxDataSource ();
ds. setIfxIFX_LOCK_MODE_WAIT (65); // 等待 65 秒
…
int waitMode = ds.getIfxIFX_LOCK_MODE_WAIT ();
示例 2
An example Using DataSource:
IfxDataSource ds = new IfxDataSource ();
ds.setIfxIFX_ISOLATION_LEVEL ("0U"); // set isolation to dirty read with
retain
// update locks.
….
String isoLevel = ds.getIfxIFX_ISOLATION_LEVEL ();
DriverManager.getConnection() 方法
要创建至 GBase 8s 数据库或数据库服务器的连接，可使用 DriverManager.getConnection() 方法。此方法用于创建 SQL 语句的Connection 对象，将它们发送至 GBase 8s 数据库，并处理结果。
DriverManager类跟踪可用的驱动程序，并处理驱动程序与数据库或数据库服务器之间的请求。getConnection() 方法的 url 参数是一个数据库 URL，其指定子协议（数据库连接性机制）、数据库或数据库服务器标识符，以及属性列表。
getConnection() 方法的第二个参数 property 是属性列表。要了解如何指定属性列表的示例，请参阅 指定属性。
下列示例展示从客户机应用程序连接至名为testDB 的数据库 URL：
jdbc:gbasedbt-sqli://123.45.67.89:1533/testDB:
GBASEDBTSERVER=myserver;user=rdtest;password=test
在下一部分中，描述数据库 URL 语法的详细信息。
下列 CreateDB.java 程序的部分示例，展示如何通过使用 DriverManager.getConnection() 来连接至数据库 testDB。在完整的示例中，当在命令行运行程序时，将前面示例中描述的 url 变量作为参数传递。
try
{
conn = DriverManager.getConnection(url);
}
catch (SQLException e)
{
System.out.println("ERROR: failed to connect!");
System.out.println("ERROR: " + e.getMessage());
e.printStackTrace();
return;
}
GBase 8s JDBC Driver 唯一支持的 GBase 8s 连接类型是 tcp。不支持共享内存和其他连接类型。要获取关于连接类型的更多信息，请参阅数据库服务器的《GBase 8s 管理员指南》。
GBase 8s JDBC Driver 并不支持 Connection 接口的所有方法。要了解不受支持的方法列表，请参阅 不支持的方法和行为不同的方法。
数据库服务器会自动关闭连接，客户机应用程序不需要显式地关闭连接，如果应用程序正在使用服务器侧 JDBC 的数据库服务器中运行，则应该显式地关闭连接。
数据库 URL 的格式
对于来自客户机的连接，请使用下列格式来指定数据库 URL：
jdbc:gbasedbt-sqli://[{ip-address|host-name}:{port-number|server-name}][/dbname]:
GBASEDBTSERVER=servername[{;user=user;password=password]
|CSM=(SSO=database_server@realm,ENC=true)}
[;name=value[;name=value]...]
对于数据库服务器上的连接，请使用下列格式：
jdbc:gbasedbt-direct://[/dbname:;[user=user;password=password] ]
[;name=value[;name=value]...]
在前面的语法中：
- 与竖线（|）在一起的大括号（{ }）表示变量的多个选择。
- 斜体字表示变量值。
- 方括号（[ ]）表示可选的值。
- 括在方括号中的词或符号是必需的（例如，GBASEDBTSERVER=）。
在数据库 URL 中不允许空格。
例如，在客户机上，您可能使用：
jdbc:gbasedbt-sqli://123.45.67.89:1533/testDB:
GBASEDBTSERVER=myserver;user=rdtest;password=test
在服务器上，您可能使用：
jdbc:gbasedbt-direct://testDB;user=rdtest;password=test
使用服务器侧 JDBC 的连接有不同的语法。要了解详细信息，请参阅数据库服务器版本的发布说明。
下表描述数据库 URL 的变量部分，以及对等的 GBase 8s 连接属性。
| GBase 8s 连接属性 | 数据库 URL 变量 | 是否必需？ | 描述 |
|---|---|---|---|
| IFXHOST | ip-address host-name | 对于客户机侧 JDBC，必需，除非定义 SQLH_TYPE属性或使用 IFXHOST 属性；对于服务器侧 JDBC，不是必需的 | 正在运行 GBase 8s 数据库服务器的计算机的 IP 地址或主机名称。 |
| PORTNO | port-number | 对于客户机侧 JDBC，必需，必须指定 port-number 或 server-name，除非定义SQLH_TYPE 属性，或使用PORTNO 属性；对于服务器侧 JDBC，不是必需的 | GBase 8s 数据库服务器的端口号 在 /etc/services 文件中罗列该端口号。 |
| 无 | server-name | 对于客户机侧 JDBC，必需，必须指定 port-number 或 server-name，除非定义SQLH_TYPE 属性，或使用PORTNO 属性；对于服务器侧 JDBC，不是必需的 | 罗列在 /etc/services 文件中的 GBase 8s 数据库服务器的server-name。 |
| DATABASE | dbname | 不是必需的，除非是来自运行在数据库服务器中的 web 应用程序的连接 | 您想要连接至其的 GBase 8s 数据库的名称 如果未指定数据库的名称，则制作至 GBase 8s 数据库服务器的连接。 |
| GBASEDBTSERVER | server-name | 必需 | 您想要连接至其的 GBase 8s 数据库服务器的名称 |
| USER | user | 必需。必须指定用户和口令，或 SSO 的 SCM 设置。 必须指定用户和口令。 | 想要连接至 GBase 8s 数据库或数据库服务器的用户名称。 必须同时指定用户和口令，或都不指定。如果都不指定，则驱动程序调用 System.getProperty() 来获取当前正在运行应用程序的用户的名称，以及假定信任的客户机。 |
| PASSWORD | password | 必需。必须指定用户和口令，或 SSO 的 CSM 设置。 必须指定用户和口令。 | 用户的口令 必须同时指定用户和口令，或都不指定。如果都不指定，则驱动程序调用 System.getProperty() 来取得当前正在运行应用程序的用户的名称，以及假定信任的客户机。 |
| 无 | database_server@realm | 必需，必须指定用户和口令，或 SSO 的 CSM 设置。 | （SSO）访问控制的服务原则。要获取信息，请参阅 随同 GBase 8s JDBC 驱动程序来使用单点登录访问控制。 |
| 无 | name=value | 不是必需的 | 为包含在 name 变量中的 GBase 8s 环境变量指定值的名-值对，GBase 8s JDBC Driver 或 GBase 8s 数据库服务器识别它 name 变量不区分大小写。 要获取更多信息，请参阅 指定属性 和 随同 GBase 8s JDBC 驱动程序的 GBase 8s 环境变量。 |
如果 LDAP 服务器或 sqlhosts 文件通过 SQLH_TYPE 属性来提供 IP 地址、主机名称或端口号，则不必在数据库 URL 中指定它们。要获取更多信息，请参阅 动态地读取 GBase 8s sqlhosts 文件。
连接 URL 中的 IP 地址
GBase 8s JDBC Driver Version 3.0 及后来的版本支持 JDK 1.4 是 IPv6 感知的。也就是说，解析连接 URL 的代码可处理更长的（128 位模式）IPv6 地址（以及 IPv4 格式）。此 IP 地址可为 IPv6 文字，例如：
3ffe:ffff:ffff:ffff:0:0:0:12
要以 GBase 8s 来连接至 IPv6 端口，请使用系统属性，例如：
java -Djava.net.preferIPv6Addresses=true ...
以 GBase 8s JDBC Driver Version 3.0 或后来版本处理不带有 IPv6 文字的 URL 是不变的，且遗留行为是不变的。
冒号（:）是连接 URL 中的关键定界符，特别是在 IPv6 文字地址中。
必须为驱动程序创建格式良好的 URL，来识别 IPv6 文字地址。请注意，在下列示例中：
- jdbc:gbasedbt-sqli:// 是需要的。
- 环绕 8088 的冒号（:8088:）是需要的。
- 驱动程序不验证 3ffe:ffff:ffff:ffff:0::12。
- 8088 必须是 < 32k 的有效数值。
jdbc:gbasedbt-sqli://3ffe:ffff:ffff:ffff:0::12:8088:gbasedbtserver=X...
数据库与数据库服务器连接
使用 DriveManager.getConnection() 方法，可创建至 GBase 8s 数据库或 GBase 8s 数据库服务器的连接。
要创建至 GBase 8s 数据库的连接，请指定 URL中 dbname 变量的数据库名称。如果省略数据库的名称，则表示至数据库服务器的连接，由数据库 URL的 GBASEDBTSERVER 环境变量或连接属性列表来指定该数据库服务器。
如果直接连接至 GBase 8s 数据库服务器，则可在 Java™ 程序中执行连接至数据库的 SQL 语句。
同时连接至数据库和数据库服务器的所有连接都必须通过GBASEDBTSERVER 环境变量来包括 GBase 8s 数据库服务器的名称。
DriverManager.getConnection() 方法 中给出的示例展示如何以数据库 URL 来创建直接连接至名为testDB 的 GBase 8s 数据库。
下列来自 DBConnection.java 程序的示例展示如何首先创建至名为 myserver 的 GBase 8s 数据库服务器的连接，然后，通过使用Statement.executeUpdate() 方法来连接至数据库 testDB。
当在命令行运行程序时，将下列数据库 URL 作为参数传给程序；请注意，URL 不包括数据库的名称：
jdbc:gbasedbt-sqli://123.45.67.89:1533:GBASEDBTSERVER=myserver;user=rdtest;password=test
代码为：
String cmd = null;
int rc;
Connection conn = null;
try
{
Class.forName("com.gbasedbt.jdbc.Driver");
}
catch (Exception e)
{
System.out.println("ERROR: failed to load GBase 8s JDBC driver.");
}
try
{
conn = DriverManager.getConnection(newUrl);
}
catch (SQLException e)
{
System.out.println("ERROR: failed to connect!");
e.printStackTrace();
return;
}
try
{
Statement stmt = conn.createStatement();
cmd = "database testDB;";
rc = stmt.executeUpdate(cmd);
stmt.close();
}
catch (SQLException e)
{
System.out.println("ERROR: execution failed - statement:
" + cmd);
System.out.println("ERROR: " + e.getMessage()); }
指定属性
当使用 DriverManager.getConnection() 方法来创建连接时，GBase 8s JDBC Driver 仅从连接数据库 URL 中的名-值对，或从连接属性列表读取GBase 8s 环境变量。驱动程序不为任何环境变量查询用户环境。
要在连接数据库 URL 的名-值对中指定 GBase 8s 环境变量，请参阅 数据库 URL 的格式。
要通过属性列表来指定 GBase 8s 环境变量，请使用 java.util.Properties 类来构建属性的列表。该属性的列表可能包括 GBase 8s 环境变量，诸如GBASEDBTSERVER，以及 user和password。
在构建了属性列表之后，将它作为第二个参数传给 DriverManager.getConnection() 方法。您仍需包括数据库 URL 作为第一个参数，尽管在此情况下您不需要在 URL 中包括属性的列表。
下列来自 optofc.java 示例的代码展示如何使用 java.util.Properties 类来设置连接属性。它首先使用 Properties.put() 方法来在连接属性列表中将环境变量OPTOFC 设置为 1；然后，它连接至该数据库。
在此示例中的 DriverManager.getConnection() 方法需要两个参数：数据库 URL 和属性列表。该示例创建类似于DriverManager.getConnection() 方法 中给出的示例的连接。
当在命令行运行程序时，将下列数据库 URL 作为参数传给示例程序：
jdbc:gbasedbt-sqli://myhost:1533:gbasedbtserver=myserver;user=rdtest;password=test
代码为：
try
{
Class.forName("com.gbasedbt.jdbc.Driver");
}
catch (Exception e)
{
System.out.println("ERROR: failed to load GBase 8s JDBC driver.");
}
try
{
Properties pr = new Properties();
pr.put("OPTOFC","1");
conn = DriverManager.getConnection(newUrl, pr);
}
catch (SQLException e)
{
System.out.println("ERROR: failed to connect!");
}
随同 GBase 8s JDBC 驱动程序的 GBase 8s 环境变量
下表罗列客户机 JDBC 驱动程序支持的大多数 GBase 8s 环境变量。对于服务器侧 JDBC，请使用数据库 URL 中的参数设置，而不设置环境变量，因为环境变量会应用于数据库服务器中运行的所有程序。要获取更多关于属性的信息，请参阅 指定属性。
要了解提供全球化特性的环境变量列表，请参阅 全球化和日期格式。要了解用于故障排除的环境变量列表，请参阅 调优和故障排除。
| 受支持的 GBase 8s 环境变量 | 描述 |
|---|---|
| APPENDISAM | 当设置为 TRUE 时，APPENDISAM 环境变量将 ISAM 错误代码和消息（如果出现的话）附加至 SQL 异常消息，当调用 SQL 异常的 .toString() 或 .getMessage() 时展示。以下列格式展示该异常消息： <GBase 8s ERROR MESSAGE> (<GBase 8s CODE>) ISAM error: |
| CSM | 指定要使用的“通讯支持模块”。 GBase 8s JDBC Driver 3.0 和后来的版本支持加密 CSM。要获取更多信息，请参阅 加密选项。 |
| DBANSIWARN | 当设置为 1 时，请检查对 ANSI 标准语法的 GBase 8s 扩展 |
| DBSPACETEMP | 指定在其中构建临时表的 dbspace |
| DBTEMP | 指定您想要 GBase 8s Enterprise Gateway 产品将它们的临时文件和临时表置于其内的目录的完整路径名称。 驱动程序不使用此变量；它只是将该值传至服务器。 |
| DBUPSPACE | 当它在 sqexplain.out 文件中构建多列分布，或者以索引排序，以及或者为计算列分布来保存规划时，指定 UPDATE STATISTICS 语句可用于行排序所需的磁盘空间和内存的数量。 |
| DELIMIDENT | 当设置为 Y 时，指定由双引号划分的字符串为定界的标识符 |
| ENABLE_TYPE_CACHE | 当设置为 TRUE 时，为 opaque、distinct 或 row 数据类型高速缓存数据类型信息。 当 Struct 或 SQLData 对象将数据插入至列内，且 getSQLTypeName() 返回类型名称时，驱动程序使用高速缓存了的信息，而不是查询数据库服务器。 |
| ENABLE_HDRSWITCH | 当设置为 TRUE 时，如果主服务器不可用，则使用辅助服务器属性来连接至辅助服务器。 |
| FET_BUF_SIZE | 对于除大对象之外的所有数据，覆盖访存缓冲区大小的缺省设置 缺省大小为 4096 字节。在服务器侧 JDBC 中不支持此变量。 |
| IFX_AUTOFREE | 当设置为 1 时，如果在数据库服务器中已关闭了游标，则指定 Statement.close() 方法不需要网络往返地释放数据库服务器游标资源。 在由 ResultSet.close() 方法显式地关闭游标之后，或通过 OPTOFC 环境变量隐式地关闭游标之后，数据库服务器自动释放游标资源。在已释放了游标资源之后，不可再引用该游标。要获取更多信息，请参阅 “自动释放”特性。 |
| IFX_BATCHUPDATE_PER_SPEC | 当设置为 1（缺省值）时，返回 SQL 语句影响的行数，通过 executeBatch() 方法，在批量操作中执行该语句 |
| IFX_CODESETLOB | 如果设置为大于或等于 0 的数值，则在客户机与数据库语言环境之间自动进行 TEXT 与 CLOB 数据类型的代码集转换。此变量的值确定是在内存中还是在临时文件中来进行代码集转换。如果设置为 0，则代码集转换使用临时文件。如果设置为大于 0 的值，则代码集转换发生在客户机计算机的内存中，且该值表示为转换分配的内存字节数。要获取更多信息，请参阅 使用 IFX_CODESETLOB 环境变量转换。 |
| IFX_DIRECTIVES | 确定优化器是否允许来自查询内的查询优化伪指令。在客户机上设置此值。驱动程序不使用此变量；它只是将该值传至服务器。 |
| IFX_EXTDIRECTIVES | 指定查询优化器是否允许将来自 sysdirectives 系统目录表的外部查询优化伪指令应用于现有的应用程序中。 缺省值为 OFF。可能的值： ON 接受外部优化器伪指令 OFF 不接受外部优化器伪指令 1 接受外部优化器伪指令 0 不接受外部优化器伪指令 |
| IFX_GET_SMFLOAT_AS_FLOAT | 当设置为 0（缺省值）时，将 GBase 8s SMALLFLOAT 数据类型映射至 JDBC REAL 数据类型。此设置符合 JDBC 规范。当设置为 1 时，将 GBase 8s SMALLFLOAT 数据类型映射至 JDBC FLOAT 数据类型。此设置使得能够与较早版本的 GBase 8s JDBC Driver 相兼容。 |
| IFX_ISOLATION_LEVEL | 定义在尝试同时访问同一行的进程之中的并发程度。取得 IFX_ISOLATION_LEVEL 变量的值，其特定于 GBase 8s 。缺省值为 2（Committed Read）。如果显式地设置了该值，则它返回设置的值。返回：整数。 设置 IFX_ISOLATION_LEVEL 变量的值，其特定于 GBase 8s 。可能的值： 0 等同于 TRANSACTION_NONE 1 Dirty Read （等同于 TRANSACTION_READ_UNCOMMITTED）， 2 Committed Read（等同于 TRANSACTION_READ_COMMITTED）， 3 Cursor Stability（等同于 TRANSACTION_READ_COMMITTED）， 4 Repeatable Read（等同于 TRANSACTION_REPEATABLE_READ） 5 Committed Read LAST COMMITTED（等同于TRANSACTION_LAST_COMMITTED） 8 等同于 TRANSACTION_SERIALIZABLE 在模式之后指定 U 意味着保留更新锁。（请参阅表后的重要说明。）例如，值会为：2U（等同于 SET ISOLATION TO COMMITTED READ RETAIN UPDATE LOCKS） 下列示例展示您将用于指定隔离级别的代码： conn.setTransactionIsolation (IfxConnection.TRANSACTION_LAST_COMMITTED); |
| IFX_FLAT_UCSQ | 覆盖全局设置，并指导优化器对所有会话使用子查询扁平化。缺省值为 1。 |
| IFX_LOCK_MODE_WAIT | 应用程序可使用此属性来覆盖用于访问锁定的行或表的缺省服务器进程。取得 IFX_LOCK_MODE_WAIT 变量的值，其特定于 GBase 8s 。缺省值为 0（不等待锁）。如果显式地设置了该值，则它返回设置的值。返回：整数。 设置 IFX_LOCK_MODE_WAIT 变量的值，其特定于 GBase 8s 。可能的值： -1 等待，直到释放锁为止。 0 不等待，结束操作，并返回错误。 nn 等待释放锁 nn 秒。 |
| IFX_PAD_VARCHAR | 当使用 Connection 类时，可在连接 URL 上设置，或当使用 DataSource 类时，设置作为属性。有效值为 0（缺省值）和 1。 ● 当设置为 0 时，仅传送包含数据的 VARCHAR 的一部分（截去后跟的空格）。 ● 当设置为 1 时，将整个 VARCHAR 数据结构在服务器间传送。 |
| IFX_SET_FLOAT_AS_SMFLOAT | 当设置为 0（缺省值）时，将 JDBC FLOAT 数据类型映射至 GBase 8s FLOAT 数据类型。此设置符合 JDBC 规范。当设置为 1 时，将 JDBC FLOAT 数据类型映射至 GBase 8s SMALLFLOAT 数据类型。此设置使得能够与较早版本的 GBase 8s JDBC Driver 兼容。 |
| IFX_TRIMTRAILINGSPACES | 移除后跟的空格。缺省值为 0。 |
| IFX_USEPUT | 当设置为 1 时，启用批量插入。要获取更多信息，请参阅 执行批量插入。 |
| IFX_XASPEC | 当设置为 y 时，紧密地结合带有相同全局 ID 的 XA 事务，并分享锁空间。这仅适用于 XA 连接，且不可在数据库 URL 中指定。通过 DataSource setter（请参阅DataSource 扩展），或通过设置带有相同名称的 System (JVM) 属性，可设置它。DataSource 属性覆盖 System 属性。忽略y、Y、n 或 N 之外的属性值。IfxDataSource.getIfxIFX_XASPEC 返回最终的 IFX_SPEC 值，其或为 y 或为 n。例如，如果 DataSource IFX_XASPEC 的值等于 n 且 System IFX_XASPEC 的值等于 Y 或 y，则返回 n。 |
| IFX_XASTDCOMPLIANCE_XAEND | 当返回 XA_RB* 时，指定 XA_END 的行为。 0 不忘记 XID。事务处于 Rollback Only 状态。这符合 XA_SPEC+，且是 GBase 8s的默认行为。 1 忘记 XID。事务为 Nonexistent。 要获取更多信息，请参阅《GBase 8s SQL 指南：参考》 DISABLE_B162428_XA_FIX (IDS 10.0) ENABLE_B162428_XA_FIX (IDS 9.40) |
| IFXHOST | 设置主机名称和主机 IP 地址 |
| IFXHOST_SECONDARY | 设置辅助主机名称和主机 IP 地址，用于 HAC 连接重定向 |
| GBASEDBTCONRETRY | 指定附加的连接尝试的最大数，在由 GBASEDBTCONTIME 的值指定的时间限制期间，客户机可尝试连接至每一数据库服务器 |
| GBASEDBTCONTIME | 为连接至数据库服务器的尝试设置超时期间。如果在此期间连接尝试不成功，则终止尝试，并报告连接错误。缺省值为 0 秒。此变量为阻塞 socket 方法以及为 socket 连接添加超时。 |
| GBASEDBTOPCACHE | 为客户机应用程序的 staging-area blobspace 指定内存高速缓存的大小 |
| GBASEDBTSERVER | 指定客户机应用程序对其进行显式或隐式连接的缺省数据库服务器 |
| GBASEDBTSERVER_SECONDARY | 指定 HAC 对中的辅助数据库服务器，如果主数据库服务器不可用，则由客户机应用程序对其进行显式或隐式连接。 |
| GBASEDBTSTACKSIZE | 指定以 KB 计的堆栈大小，数据库服务器将其用于特殊的客户机会话 |
| JDBCTEMP | 指定在哪里创建用于处理智能大对象的临时文件。您必须提供绝对路径名称。 |
| LOBCACHE | 确定从数据库服务器访存的大对象数据的缓冲区大小。可能的值为： 大于 0 的数值 在内存中分配来保存数据的最大字节数。如果数据大小超过 LOBCACHE 值，则将数据存储在临时文件中；如果在创建此文件期间发生安全违规，则将数据存储在内存中。 零 始终将数据存储在文件中。如果发生安全违规，则驱动程序不尝试在内存中存储数据。 负数 始终将数据存储在内存中。如果得不到所需的内存量，则发生错误。 如果未指定 LOBCACHE 值，则缺省为 4096 字节。 |
| LOGINTIMEOUT | 确定 GBase 8s 数据库服务器是否正在运行。如果服务器正在运行，则立即建立至服务器的连接。如果服务器未运行，则此环境变量指定监听该服务器端口多少毫秒，以建立连接。如果在指定的时间内，您的应用程序未连接至 GBase 8s 数据库服务器，则返回错误。 |
| NEWNLSMAP | 允许在 NLS 与 JDK 语言环境以及要定义的 JKD 代码集之间映射。 要获取更多信息，请参阅 用户定义的语言环境。 |
| NODEFDAC | 当在未以 LOG MODE ANSI 创建了的数据库中创建新的表或 UDR 时，在缺省情况下，防止 PUBLIC 组接收表或例程权限。必需的 yes 设置是区分大小写的。 |
| OPT_GOAL | 指定优化器的查询性能目标。在启动应用程序之前，请在用户环境中设置此变量。驱动程序不使用此变量；它只是将该值传给服务器。 |
| OPTCOMPIND | 指定查询优化器使用的连接方法 |
| OPTOFC | 当设置为 1 时，如果在客户机元组缓冲区中已检索了所有符合条件的行，则 ResultSet.close() 方法不需要网络往返。在检索了所有行之后，数据库服务器自动关闭游标。在调用下一ResultSet.next() 方法之前，在客户机元组缓冲区中，GBase 8s JDBC Driver 可能没有附加的行。因此，除非 GBase 8s JDBC Driver 已从数据库服务器接收了所有行，否则，当设置 OPTOFC 为 1 时，ResultSet.close() 方法可能仍需要网络往返。 |
| PATH | 为可执行程序指定要搜索的目录 |
| PDQPRIORITY | 确定数据库服务器使用的并行程度 |
| PORTNO_SECONDARY | 指定 HAC 对中辅助数据库服务器的端口号。该端口号罗列在 /etc/services 文件中。 |
| PROXY | 指定 HTTP 代理服务器。要获取更多信息，请参阅 HTTP 代理服务器。 |
| PSORT_DBTEMP | 指定当执行排序时，数据库服务器将它使用的临时文件写至的一个或多个目录 |
| PSORT_NPROCS | 通过为排序分配更多线程，来使得数据库服务器能够提高并行处理排序包的性能 |
| SECURITY | 使用 56 位加密来将口令发送至服务器。要获取更多信息，请参阅 口令加密。 |
| SQLH_TYPE | 当设置为 FILE 时，指定在 sqlhosts 文件中指定的数据库信息（诸如 host-name、port-number、user 和 password）。 当设置为 LDAP 时，指定在 LDAP 服务器中指定此信息。要获取更多信息，请参阅 动态地读取 GBase 8s sqlhosts 文件。 |
| SQLIDEBUG | 指定要将二进制 SQLI 踪迹写至其中的文件的路径名称。为每个连接生成新的踪迹文件，并以时间戳做前缀。当受到 GBase 技术支持代表指导时，请仅使用 SQLI 踪迹功能。 |
| SRV_FET_BUF_SIZE | 在与其他数据库服务器的分布式事务中，覆盖访存缓冲区大小的缺省设置。例如，该访存缓冲区保存由跨服务器分布式查询检索的数据。 |
| STMT_CACHE | 当设置为 1 时，使得在会话中能够使用共享语句高速缓存。 此特性可减少内存消耗，并提高不同用户会话之间的查询处理速度。驱动程序不使用此变量；它只是将该值传给服务器。 |
| TRUSTED_CONTEXT | 当设置为 TRUE 时，从客户机发送受信的连接请求。或者建立成功的受信连接，或者从服务器返回下列错误：SQL Exception: -28021(Trusted Connection request rejected.) |
| DB_LOCALE | 数据库字符集 例：DB_LOCALE= zh_CN.utf8; |
| CLIENT_LOCALE | 客户端字符集 例：CLIENT_LOCALE=zh_CN.utf8; |
| SQLMODE | 数据库模式，缺省为gbase模式 例：SQLMODE=oracle; |
| PROTOCOLTRACEFILE | 跟踪信息的文件路径 |
| PROTOCOLTRACE | 调试级别 |
要获取特殊环境变量的详尽描述，请参阅 《GBase 8s SQL 指南：参考》。
代码示例 IFX_LOCK_MODE_WAIT 环境变量
IFX_LOCK_MODE_WAIT
Connection conn = DriverManager.getConnection ( "jdbc:GBASEDBT-sqli://cleo:1550:
GBASEDBTSERVER=cleo_921;IFXHOST=cleo;PORTNO=1550;user=rdtest; password=my_passwd;
IFX_LOCK_MODE_WAIT=1";);
代码示例 IFX_ISOLATION_LEVEL 环境变量
IFX_ISOLATION_LEVEL
Connection conn = DriverManager.getConnection( "jdbc:GBASEDBT-sqli://cleo:1550:
GBASEDBTSERVER=cleo_921;IFXHOST=cleo;PORTNO=1550;user=rdtest; password=my_passwd;
IFX_ISOLATION_LEVEL=1U";);
当它是至数据库的显式连接时，可在 URL 中设置隔离属性。对于仅限于服务器的连接，在连接时刻忽略此属性。
代码示例 IFX_ISOLATION_LEVEL 环境变量
Connection conn = DriverManager.getConnection( "jdbc:gbasedbt-sqli://localhost:9088
/csdk_db:GBASEDBTSERVER=ol_ids_1150_1;user=gbasedbt;password=inform123;
LOGINTIMEOUT=60000";);
动态地读取 GBase 8s sqlhosts 文件
GBase 8s JDBC Driver 支持 JNDI（Java™ 命名和目录接口）。此支持使得 JDBC 程序能够访问 GBase 8s sqlhosts 文件。sqlhosts 文件允许客户机应用程序找到并连接至网络上任何位置的 GBase 8s 数据库服务器。要获取关于此文件的更多信息，请参阅《GBase 8s 管理员指南》。
您可从本地文件或从 LDAP 服务器来访问 sqlhosts 数据。系统管理员必须使用 GBase 8s 实用程序，来将 sqlhosts 数据加载至 LDAP 服务器内。
您的 CLASSPATH 变量必须引用 JNDI JAR（Java 归档）文件和 LDAP SPI（服务提供商接口）JAR 文件。您必须使用 LDAP Version 3.0 或更新的版本，其支持对象类 extensibleObject。
您可使用 sqlhosts 文件 group 选项，来为 GBASEDBTSERVER 的值指定数据库服务器组的名称。group 选项对“高可用性数据复制”（ HAC）非常有用；顺序地在 HAC 对中罗列主和辅助数据库服务器。要获取关于如何设置和使用 sqlhosts 文件中的组的更多信息，请参阅《GBase 8s 管理员指南》。要获取关于 HAC 的更多信息，请参阅 连接至高可用性集群的服务器。
未签名的 applet 不可访问 sqlhosts 文件或 LDAP 服务器。要获取更多信息，请参阅 在 applet 中使用驱动程序。
连接属性语法
您可允许 GBase 8s JDBC Driver 查找 LDAP 服务器中的主机名称和端口号，而不是在数据库 URL 或 DataSource 对象中直接指定它们。必须为 LDAP 服务器指定数据库 URL 或 DataSource 对象中的下列属性：
-
SQLH_TYPE=LDAP
-
LDAP_URL=ldap://host-name:port-number
host-name 和 port-number 是 LDAP 服务器的属性，不是数据库服务器。
-
LDAP_IFXBASE=GBASEDBT-base-DN
-
LDAP_USER=user
-
LDAP_PASSWD=password
如果未指定LDAP_USER 和LDAP_PASSWD，则 GBase 8s JDBC Driver 使用匿名搜索来搜索 LDAP 服务器。LDAP 管理员必须确保在 sqlhosts条目上允许匿名搜索。要获取更多信息，请参阅您的 LDAP 服务器资料。
GBASEDBT-base-DN 有下列基本格式：
cn=common-name,o=organization,c=country
如果 common-name、organization 或 country 由多个词组成，则可为每一词使用一个条目。例如：
cn=gbasedbt,cn=software
这里是一个示例数据库 URL：
jdbc:gbasedbt-sqli:gbasedbtserver=value;SQLH_TYPE=LDAP;
LDAP_URL=ldap://davinci:329;LDAP_IFXBASE=cn=gbasedbt,
cn=software,o=kmart,c=US;LDAP_USER=abcd;LDAP_PASSWD=secret
您还可在数据库 URL 或DataSource 对象中指定 sqlhosts 文件。从 sqlhosts 文件读取 GBase 8s 数据库服务器的主机名称和端口号或服务名称，如同在 /etc/services 文件中指定的那样。必须为该文件指定下列属性：
SQLH_TYPE=FILE
SQLH_FILE=sqlhosts-filename
sqlhosts 文件可以是本地的或远程的，因此，您可以本地系统文件格式或以 URL 格式来引用它。这里是一些示例：
SQLH_FILE=http://host-name:port-number/sqlhosts.ius
SQLH_FILE=http://host-name:service-name/sqlhosts.ius
GBase 8s 数据库服务器（来自 etc/services 文件）元素的 host-name 和 port-number 或 service-name 是在其上驻留 sqlhosts 文件的服务器的那些属性。
SQLH_FILE=file://D:/local/myown/sqlhosts.ius
SQLH_FILE=/u/local/sqlhosts.ius
这里是示例数据库 URL：
jdbc:gbasedbt-sqli:gbasedbtserver=value;SQLH_TYPE=FILE;
SQLH_FILE=/u/local/sqlhosts.ius
如果数据库 URL 或 DataSource 对象引用 LDAP 服务器或 sqlhosts 文件，而且直接指定 IP 地址、主机名称和端口号，则在数据库 URL 或DataSource 对象中指定的 IP 地址、主机名称和端口号优先。要获取关于如何通过使用 DataSource 对象来设置这些连接属性的信息，请参阅DataSource 扩展。
如果您正在使用 applet 或位于防火墙之后的数据库，则需要运行在额外层中的 HTTP 代理服务器，用于通讯。要获取更多信息，请参阅 HTTP 代理服务器。
管理要求
如果您想要 LDAP 服务器来存储 JDBC 可查找的 sqlhosts 信息，则必须满足下列要求：
- 必须在客户机可访问的计算机上安装 LDAP 服务器。LDAP 管理员必须在 LDAP 服务器中创建 BASE 条目。
- 如果您想要使用 GBase 8s SqlhUpload 和 SqlhDelete 实用程序，其可从文本 ASCII 文件加载或删除 sqlhosts 条目，则 sqlhosts 文件中的 servicename 字段必须指定数据库服务器端口号。要获取更多信息，请参阅 以 sqlhosts 数据来更新 LDAP 服务器的实用程序。
- LDAP 管理员必须确保在 sqlhosts 条目上允许匿名搜索。要获取更多信息，请参阅 LDAP 服务器资料。
以 sqlhosts 数据来更新 LDAP 服务器的实用程序
在 gbasedbtjdbc_xx.jar 中包装 SqlhUpload 和 SqlhDelete 实用程序，因此，CLASSPATH 变量必须指向 gbasedbtjdbc_xx.jar（在缺省情况下，其位于 GBase 8s JDBC Driver 的安装目录之下的 lib 目录中）。请确保 CLASSPATH 变量也指向 JNDI JAR 文件和 LDAP SPI JAR 文件。
SqlhUpload 实用程序
此实用程序以规定的格式，从文本 ASCII 文件将 sqlhosts 条目加载至 LDAP 服务器。
输入下列命令：
java SqlhUpload sqlhfile.txt host-name:port-number [sqlhostsRdn]
参数有下列含义：
- 要上载的 sqlhosts 文件为 sqlhfile.txt。
- LDAP 服务器的主机名称和端口号为 host-name:port-number。
- 在 LDAP 中 GBase 8s 基础之下的 sqlhosts 节点的 RDN®（相对可分辨名称）为 sqlhostsRdn。缺省名称为 sqlhosts。
实用程序提示提供其他必需的的信息，诸如 LDAP 服务器中的 GBase 8s 基础可分辨名称（DN）、LDAP 用户和口令。
您必须将 sqlhosts 文件中的 servicename 字段转换为表示整数（端口号）的字符串，因为 Java™.Socket 类不可接受端口号的字母数字的 servicename 值。要获取关于 servicename 字段的更多信息，请参阅《GBase 8s 管理员指南》 。
SqlhDelete 实用程序
此实用程序从 LDAP 服务器删除 sqlhosts 条目。请输入下列命令：
java SqlhDelete host-name:port-number [sqlhostsRdn]
此命令的参数与为 SqlhUpload 实用程序罗列的参数有相同的含义。请参阅 SqlhUpload 实用程序。
实用程序提示提供其他必需的的信息，诸如 LDAP 服务器中的 GBase 8s 基础 DN、LDAP 用户和口令。
连接至高可用性集群的服务器
使用 JDBC 驱动程序，Java™ 应用程序可连接至高可用性集群中的 GBase 8s 数据库服务器。Java 应用程序还可连接至 GBase 8s Connection Managers，其可为高可用性集群处理故障转移，并将连接重定向至集群服务器。
Java 应用程序要连接至高可用性集群的服务器，您必须在连接 URL 或 DataSource 中设置属性。如果应用程序在辅助服务器上执行更新操作，则请配置应用程序来初始地检查只读服务器状态。
当您配置 GBase 8s Connection Managers 来处理 Java 应用程序服务器与高可用性集群之间的连接时，可获得下列好处：
- 通过基于规则的重新指向策略，将连接请求指向最正确的辅助服务器。
- 您可为高可用性集群管理故障转移，如果主服务器故障，则自动地将一辅助服务器提升为主服务器的角色。
- 当您在与 Java 应用程序服务器相同的主机上安装并配置 GBase 8s Connection Managers 时，可在特定的应用程序服务器与高可用性集群的主服务器之间排出优先级。
- 当数据库服务器位于防火墙之后时，GBase 8s Connection Managers 可担当代理服务器，并处理客户机/服务器通讯。
可使用带有连接池的高可用性辅助服务器。要获取更多信息，请参阅 高可用数据复制与连接池。
通过 GBase 8s Connection Manager 连接至高可用性集群服务器的属性
JDBC 应用程序可连接至 Connection Manager，就像应用程序可能连接至数据库服务器一样。然后，将应用程序连接请求重新指向高可用性集群中最恰当的服务器。
可配置多个 Connection Manager，然后在 Java™ 应用程序服务器使用的 sqlhost 文件中创建一 Connection Manager 组条目。如果一个 Connection Manager 故障，则可将连接请求指向正在工作的 Connection Manager。SQLH_FILE 连接属性指导 JDBC 驱动程序搜索组条目。
要连接至一 GBase 8s Connection Manager，然后再通过其连接至高可用性集群的服务器，您必须在连接 URL 或 DataSource 中包括下列属性：
GBASEDBTSERVER=CM_or_group_name
SQLH_TYPE=FILE
SQLH_FILE=sqlhosts
USER=user_name
PASSWORD=password
如果 Connection Manager 正在运行，但有一个挂起的连接，则在连接 URL 中包括下列属性，可防止 Java 应用程序无限地等待。
GBASEDBTCONRETRY=value
GBASEDBTCONTIME=value
LOGINTIMEOUT=value
基于网络环境来设置这些值。
示例 1：通过 GBase 8s Connection Manager 来连接至高可用性集群
在此示例中，您有下列系统设置：
-
由四个服务器组成的高可用性集群（my_cluster）。
-
所有集群服务器上的用户名都是my_user。
-
所有集群服务器上的口令都是my_password。
-
cmhost1.example.com 上的 connection_manager使用下列配置文件：
NAME connection_manager
CLUSTER my_cluster
{
GBASEDBTSERVER my_servers
SLA sla_primary DBSERVERS=PRI
SLA sla_secondaries DBSERVERS=SDS,HDR,RSS
} -
在host1.example.com上有一 Java 应用程序服务器，该 Java 应用程序服务器使用下列 sqlhost 文件条目：
#dbservername nettype hostname servicename options
sla_primary onsoctcp cmhost1.example.com cm_port_1
sla_secondaries onsoctcp cmhost1.example.com cm_port_1 -
如果客户机的初始连接尝试失败，则想要它再试两次。
-
想要 CONNECT 语句等待 10 秒，来建立连接。
-
如果侦听服务器端口，且在 10 毫秒之内未连接，则想要连接失败。
要 Java 应用程序客户机连接至 my_cluster 的主服务器，请使用下列 URL：
jdbc:gbasedbt-sqli://GBASEDBTSERVER=sla_primary;
SQLH_TYPE=FILE;SQLH_FILE=sqlhosts;
USER=my_user_name;PASSWORD=my_password;
GBASEDBTCONRETRY=2;GBASEDBTCONTIME=10;LOGINTIMEOUT=10
要 Java 应用程序客户机连接至 my_cluster 的辅助服务器，请使用下列 URL：
jdbc:gbasedbt-sqli://GBASEDBTSERVER=sla_secondaries;
SQLH_TYPE=FILE;SQLH_FILE=sqlhosts;
USER=my_user_name;PASSWORD=my_password;
GBASEDBTCONRETRY=2;GBASEDBTCONTIME=10;LOGINTIMEOUT=10
示例 2：通过多个 GBase 8s Connection Manager 连接至高可用性集群
在此示例中，您有下列系统设置：
-
由四个服务器组成的高可用性集群（my_cluster）。
-
所有集群服务器上的用户名都是 my_user。
-
所有集群服务器上的口令都是 my_password。
-
cmhost1.example.com 上的 connection_manager_1 使用下列配置文件，用于客户机重新指向和故障转移：
NAME connection_manager_1
CLUSTER my_cluster
{
GBASEDBTSERVER my_servers
SLA sla_primary_1 DBSERVERS=PRI
FOC ORDER=ENABLED \
PRIORITY=1
CMALARMPROGRAM $GBS_HOME/etc/CMALARMPROGRAM.sh
} -
cmhost2.example.com 上的 connection_manager_2 使用下列配置文件，用于客户机重新指向和故障转移：
NAME connection_manager_2
CLUSTER my_cluster
{
GBASEDBTSERVER my_servers
SLA sla_primary_1 DBSERVERS=PRI
FOC ORDER=ENABLED \
PRIORITY=2
CMALARMPROGRAM $GBS_HOME/etc/CMALARMPROGRAM.sh
} -
在 host1.example.com 上有一 Java 应用程序服务器，且 Java 应用程序服务器使用下列 sqlhost 文件条目：
#dbservername nettype hostname servicename options
g_primary group - - c=1,e=sla_primary_2
sla_primary_1 onsoctcp cmhost1.example.com cm_port_1 g=g_primary
sla_primary_2 onsoctcp cmhost2.example.com cm_port_2 g=g_primary -
如果客户机的初始连接尝试失败，则想要它重试两次。
-
想要 CONNECT 语句等待 10 秒，来建立连接。
-
如果侦听服务器端口，且在 10 毫秒之内未连接，则想要连接失败。
要通过 connection_manager_1 或 connection_manager_2，Java 应用程序客户机连接至 my_cluster 的主服务器，请使用下列 URL：
jdbc:gbasedbt-sqli://GBASEDBTSERVER=g_primary;
SQLH_TYPE=FILE;SQLH_FILE=sqlhosts;
USER=my_user_name;PASSWORD=my_password;
GBASEDBTCONRETRY=2;GBASEDBTCONTIME=10;LOGINTIMEOUT=10
通过 SQLHOST 文件组条目，来连接至高可用性集群服务器的属性
您可定义 sqlhost 组条目，以便于始终将应用程序连接尝试指向高可用性集群的主服务器，即使发生故障转移。
要连接至高可用性集群的主服务器，请在连接 URL 或 DataSource 中包括下列属性：
GBASEDBTSERVER=group_name
SQLH_TYPE=FILE
SQLH_FILE=sqlhosts
USER=user_name
PASSWORD=password
如果 JDBC 驱动程序未能在该组中找到主服务器，则抛出异常。
为 GBase 8s 启用至主服务器的强制连接。
示例：通过 SQLHOST 文件组条目来连接至高可用性集群的主服务器
在此示例中，有下列系统设置：
-
由四个服务器组成的高可用性集群（my_cluster）：
- host1.example.com 上的 server_1（主）
- host1.example.com 上的 server_2（共享磁盘辅助）
- host2.example.com 上的 server_3（HAC）
- host3.example.com 上的 server_4（远程独立辅助）
-
所有集群服务器上的用户名都是 my_user。
-
所有集群服务器上的口令都是 my_password。
-
在 host4.example.com 上有一 Java™ 应用程序服务器。该服务器使用下列 sqlhost 文件条目：
#dbservername nettype hostname servicename options
my_servers - - c=1,e=server_4
server_1 onsoctcp host1.example.com port_1 g=my_servers
server_2 onsoctcp host1.example.com port_2 g=my_servers
server_3 onsoctcp host2.example.com port_3 g=my_servers
server_4 onsoctcp host3.example.com port_4 g=my_servers
要 Java 应用程序客户机连接至 my_cluster 的主服务器，请使用下列 URL：
jdbc:gbasedbt-sqli://GBASEDBTSERVER=my_servers;
SQLH_TYPE=FILE;SQLH_FILE=sqlhosts;
USER=my_user_name;PASSWORD=my_password
直接连接至服务器的 HAC 对的属性
您可定义客户机应用程序的连接 URL 或 DataSource，以便于应用程序直接地连接到服务器的 HAC 对。如果至主服务器的连接尝试失败，则客户机应用程序可尝试连接至 HAC 辅助服务器。
要直接地连接至主服务器和 HAC 辅助服务器，请在连接 URL 或 DataSource 中包括下列属性：
GBASEDBTSERVER=primary_server_name
GBASEDBTSERVER_SECONDARY=secondary_server_name
IFXHOST_SECONDARY=secondary_host_name
PORTNO_SECONDARY=secondary_port_number
USER=user_name
PASSWORD=password
ENABLE_HDRSWITCH=true
如果您正在设置 DataSource 中的值，则还必须包括下列值：
IFXHOST=primary_host_name
PORTNO=primary_port_number
当正在使用 DataSource 对象时，您可以 setXXX() 和 getXXX() 方法，来设置或取得辅助服务器连接属性。在 获取和设置 GBase 8s 连接属性中，罗列这些方法对应的连接属性。
通过编辑 DataSource 中的 GBASEDBTSERVER、PORTNO 和 IFXHOST 属性，或通过编辑 URL 中的 GBASEDBTSERVER 属性，您可手工地将连接重新指向 HAC 对中的辅助服务器。手工重新指向需要编辑应用程序代码，然后重新启动应用程序。
示例：连接至服务器的 HAC 对
下列示例展示名为 server_1 的主服务器和名为 server_2 的 HAC 辅助服务器的连接 URL：
jdbc:gbasedbt-sqli://my_host:my_port/my_database:
GBASEDBTSERVER=server_1;GBASEDBTSERVER_SECONDARY=server_2;
IFXHOST_SECONDARY=host2.example.com;PORTNO_SECONDARY=port_2;
user=my_name;password=my_password;
ENABLE_HDRSWITCH=true
检查高可用性辅助服务器的只读状态
可编写应用程序来检查只读服务器状态，以便于不对只读辅助服务器尝试更新操作。
GBase 8s JDBC 有对 java.sql.Connection 类的扩展方法，其提供检查 HAC 辅助服务器的状态的方式。用户可将连接对象强制转型为 'com.gbasedbt.jdbc.IfmxConnection' 来访问下列扩展方法。
| 获得的信息 | 方法签名 | 附加信息 |
|---|---|---|
| 服务器是否为只读（辅助服务器） | public boolean 为 ReadOnly() throws SQLException | 如果活动的服务器为辅助服务器，则返回 true 如果发生数据库访问错误，则返回异常 如果将 ENABLE_HDRSWITCH 设置为 false，则isReadOnly()返回在获得了最后一次成功的HAC 连接之后初始设置的值。 |
| 是否启用 HAC | public Boolean is HDREnabled() | 如果 HAC 对中的服务器都可用，则返回 true 如果有一个服务器不可用，则返回 false |
| 服务器的类型（主、辅助或标准） | public string getHDRtype() | 对于主服务器返回 primary 或 standard，对于辅助服务器返回 secondary 数据库管理员可手工地重置服务器的类型。 |
例如，您可使用下列策略之一：
- 在每一可能包含更新操作的 SQL 语句之前，使用 isReadOnly() 方法。如果 isReadOnly() 的值为 true，则执行恰当的行动，诸如将错误消息发送至用户，或通知服务器管理员。
- 在建立连接之后，调用 isReadOnly() 方法，然后设置像 READ_ONLY 这样的标志，然后，基于标志值来执行操作。
管理员可手工地将辅助服务器切换为主服务器，以允许更新操作。然而，必须在进程中关闭服务器，这可导致丢失未提交的事务。
对 HAC 辅助服务器的连接重试尝试
您可编写应用程序，以便于如果在查询操作期间连接丢失，则 GBase 8s JDBC Driver 将新的连接返回至辅助数据库服务器，且应用程序重新运行查询。
下列示例展示如何尝试重新与辅助服务器信息连接，然后，重新运行由于主服务器连接失败而收到错误的 SQL 语句：
public class HDRConnect {
static IfmxConnection conn;
public static void main(String[] args)
{
getConnection(args[0]);
doQuery( conn );
closeConnection();
}
static void getConnection( String url )
{
..
Class.forName("com.gbasedbt.jdbc.Driver");
conn = (IfmxConnection)DriverManager.getConnection(url);
}
static void closeConnection()
{
try
{
conn.close();
}
catch (SQLException e)
{
System.out.println("ERROR: failed to close the connection!");
return;
}
}
static void doQuery(Connection con)
{
int rc=0;
String cmd=null;
Statement stmt = null;
try
{
// execute some sql statement
}
catch (SQLException e)
{
if (e.getErrorCode() == -79716 ) || (e.getErrorCode() == -79735)
// system or internal error
{
// This is expected behavior when primary server is down
getConnection(url);
doQuery(conn);
}
else
System.out.println("ERROR: execution failed - statement: " + cmd);
return;
}
}
其他多层解决方案
在多层环境中使用 GBase 8s JDBC Driver 的其他方式如下：
“远程方法调用”（RMI）
GBase 8s JDBC Driver 驻留在作为 Java™ applet 或应用程序与 GBase 8s 数据库及其之间的中间层的应用程序服务器上。GBase 8s JDBC Driver 包括一个 RMI 的示例；要了解详细信息，请参阅 示例代码文件。
其他通讯协议，诸如 CORBA
GBase 8s JDBC Driver 驻留在作为 Java applet 或应用程序与 GBase 8s 数据库计算机的中间层的应用程序服务器上。
加密选项
您可使用口令（SECURITY=PASSWORD）或网络加密，来建立安全的连接。要使用口令选项，或要使用网络加密，您必须在 Java™ 运行时刻环境中安装符合“Java 密码技术扩展”（JCE）的加密服务提供程序。JRE 1.4 或后来的版本以及 GBase JRE 1.4.2 包包括符合 JCE 的加密服务提供程序。
建议不要在同一客户机上混用安全软件包。下列主题描述如何配置每一软件包。
不要一起使用网络加密和口令加密。因此，当使用 JDBC 加密 CSM 时，不应以 SECURITY 环境变量来启用口令加密。在将它们发送到网络之前，JDBC 加密 CSM 不加密口令。
JCE 安全软件包
已将 JCE 集成至 J2 SDK Version 1.4 内，但仅在美国和加拿大可用。如果您的站点不符合此限制或其他 JCE 许可限制，则可尝试使用带有其他 JCE 认证的安全软件包提供程序的 GBase 8s JDBC Driver。然而，请注意，并非所有软件包都已测试并认证，可以与配置了使用 SPWDCSM CSM 选项或加密 CSM 的 GBase 8s 一起工作。或者，您可使用符合 GBase FIPS 的安全软件包。
如果您正在使用 JDK 1.4 来安装 JCE 软件包，则请下载 JCE 分发，抽取包含 JCE 提供程序软件包的 .jar 文件，并将它们复制至安装 JDK 的jre/lib/ext 目录。
编辑来自 JDK 安装的 lib/security/java.security 文件，来包括下列两行：
security.provider.1=sun.security.provider.Sun
security.provider.2=com.sun.crypto.provider.SunJCE
要获取关于配置加密服务提供程序的更多详细信息，请参阅 JRE 资料。
符合 GBase FIPS 的安全软件包
GBase 1.4.2 SR1a JRE 或后来的版本包括一个称为 GBASEJCEFIPS 的 JCE 符合“联邦信息处理标准”（FIPS）140-2 软件包。作为 JCE 提供程序来实现 GBASEJCEFIPS 软件包，来通过 JCE 框架 API 支持 FIPS 批准的密码操作。可随同简单的 CSM 或随同加密 CSM 来使用 GBASEJCEFIPS 软件包。
要使用 FIPS 软件包，请将 GBASEJCEFIPS 提供程序添加至 JVM java.security 文件中的安全提供程序列表，其位于安装 JRE 的 jre/lib/ext 目录中。
必须以比 java.security 文件中任何非 FIPS 安全提供程序更高的优先顺序，来指定 GBASEJCEFIPS 提供程序。该顺序是基于 1 的，意味着 1 是最优先的，然后是 2，依此类推。
例如：
security.provider.1=com.gbase.crypto.fips.provider.GBASEJCEFIPS
security.provider.2=com.gbase.crypto.fips.provider.GBASEJCE
请确保 GBASEJCEFIPS 比 GBASEJCE 提供程序有更高的优先顺序。
无需对 GBase 8s JDBC Driver 进行任何应用程序更改，即可使用符合 FIPS 的密码软件包。
要了解关于配置加密服务提供程序的更详细信息，请在前面罗列的网站参阅 GBase Developer Kit 和 Runtime Environment 的 GBase JRE 资料。
口令加密
当 GBase 8s JDBC 客户机与 GBase 8s 数据库服务器交换数据时，SECURITY 环境变量指定执行的安全操作。在 GBase 8s JDBC Driver 中支持的SECURITY 环境变量的唯一设置是 PASSWORD。
如果指定 PASSWORD，则当将口令从客户机传至数据库服务器时，使用 56 位加密来加密用户提供的口令。没有缺省的设置。
这里是一个示例：
String URL = "jdbc:gbasedbt-sqli://158.58.10.171:1664:user=myname;
password=mypassord;GBASEDBTSERVER=myserver;SECURITY=PASSWORD";
PASSWORD 不区分大小写。
配置数据库服务器
在 GBase 8s 数据库服务器中，支持 SECURITY=PASSWORD 设置。
如果在 GBase 8s JDBC 客户机中指定 SECURITY=PASSWORD，则在 GBase 8s 数据库服务器上必须启用 SPWDCSM csm 选项。否则，在连接期间会返回错误。
要使用支持在数据库服务器上口令加密的 SPWDCSM csm 服务器选项，必须配置服务器 sqlhosts 服务器名称选项。在服务器上设置此选项之后，仅使用 SECURITY=PASSWORD 设置的客户机可连接至该服务器名称。
要查看如何配置 CSM 选项的通用详细信息，请参阅《GBase 8s 管理员指南》。
配置连接来使用 SSL 协议
要配置 GBase 8s JDBC Driver 的数据库连接，来使用“安全套接层”（SSL）协议，需要将 sslConnection 属性设置为 TRUE。
在至数据源的连接可使用 SSL 协议之前，必须在数据库服务器中将应用程序连接至的端口配置为 SSL 监听器端口。
请在 Connection 或 DataSource 实例上设置 sslConnection 属性。下列示例演示如何在 Connection 实例上设置 sslConnection 属性：
java.util.Properties properties = new java.util.Properties();
properties.put("user", "xxxx");
properties.put("password", "yyyy");
properties.put("sslConnection", "true");
java.sql.Connection con =
java.sql.DriverManager.getConnection(url, properties);
网络加密
通过使用加密通讯支持模块，GBase 8s 启用网络上的数据传输加密。通过将通讯支持模块（CSM）添加至 JDBC 驱动程序，GBase 8s JDBC Driver Version 2.21.JC5 和后来的版本使得所有 JDBC 客户机都可用此特性。
GBase 8s JDBC 加密模块是包装在 GBase 8s JDBC .jar 中的 com.gbasedbt.jdbc.Crypto 类。GBase 8s JDBC 加密 CSM 是使用来自 Java™ 密码技术提供程序的纯 Java 实现。
网络加密语法
要配置网络加密，请设置 CSM 环境变量。下列语法说明 CSM 环境变量和加密选项：
CSM 环境变量语法
option tags
指定加密标记的语法。要获取更多信息，请参阅 option 标记。
config=parameterfile
指定文件中的加密选项。要获取更多信息，请参阅 选项参数。
option 标记
可传至加密 CSM 的 option 标记与服务器或 CSDK 使用的 CSM 配置文件中指定的加密 option 标记相同。有三个 option 标记：
cipher
定义会话可使用的所有密码。
mac
定义 MAC 生成期间使用的消息认证代码（MAC）键文件，以及使用的 MAC 生成级别。
switch
定义重新商议密码或密钥的频度。保持使用密钥和加密密码的时间越长，攻击者破解加密规则的可能性越大。要避免这种情况，密码学家建议定期更改长期连接上的密钥和密码。此重新商议的缺省值为每小时一次。通过使用 switch 标记，可以分钟为单位来设置此重新商议的时间。
要了解这些标记的语法，请参阅《GBase 8s 安全指南》。
用逗号将加密 CSM 选项参数分开，而不使用分号。当使用 DataSource 时，可使用 getIfxCSM() 和 setIfxCSM() 方法来取得和设置 CSM 为属性。当设置 CSM 为属性时，请确保未在圆括号中括上 option 字符串。下列为正确地设置 CSM 为属性的示例：
connProperties.put("CSM","classname=com.gbasedbt.jdbc.Crypto,cipher[all], mac[<builtin>]");
选项参数
通过创建带有加密参数的文件，然后指定该文件名称，可配置加密。加密参数为：
- ENCCSM_CIPHERS：要使用的密码
- ENCCSM_MAC：MAC 级别
- ENCCSM_MACFILES：MAC 文件位置
- ENCCSM_SWITCH：CIPHER 和 KEY 更改频度，以逗号隔开
要了解这些参数的语法，请参阅《GBase 8s 安全指南》。
下列是在配置文件中指定 CSM 参数的示例：
String newUrl = "jdbc:gbasedbt-sqli:
//beacon:8779/test:GBASEDBTSERVER=danon950_beacon_encrypt;
user=rdtest;password=test;
csm=(classname=com.gbasedbt.jdbc.Crypto,config=test.cfg)";
try
{
Class.forName( "com.gbasedbt.jdbc.Driver" );
}catch( Exception e )
{
System.out.println( "ERROR: failed to load
GBase 8s JDBC driver." );
}
try
{
Connection con = DriverManager.getConnection( newUrl );
}
catch( SQLException e )
{
System.out.println( "ERROR: failed to connect." );
e.printStackTrace();
return;
}
在服务器中配置加密 CSM
要能在加密端口上连接至 GBase 8s 数据库服务器，JDBC 客户机必须使用 JDBC 加密 CSM。当使用 JDBC 加密 CSM 时，至未加密的端口上的 GBase 8s 数据库服务器的连接尝试失败。可能配置 GBase 8s 数据库服务器的一个实例来同时监听加密的端口和未加密的端口。要获取关于将 GBase 8s 配置为使用加密 CSM 的详细信息，请参阅《GBase 8s 管理员指南》。
关闭连接
在使用连接池与不使用连接池的环境中，下表对比调用 Connection.close() 与 scrubConnection() 方法的效果差异。
要获取关于解除资源分配的更多信息，请参阅 释放资源。要获取关于 scrubConnection() 方法的更多信息，请参阅 清除池连接。
| 连接池状态 | 调用 Connection.close() 方法的效果 | 调用 scrubConnection() 方法的效果 |
|---|---|---|
| 无连接池设置 | 关闭数据库连接、所有相关联的语句对象，以及它们的结果集。连接不再有效。 | 连接返回至原始状态，保持打开的语句，但关闭结果集，Connection 仍有效。 仅释放与结果集相关联的资源。 |
| 以 GBase 8s 实现的连接池 | 关闭至数据库的连接，并重新打开它，以关闭与连接相关联的任何语句，并将连接重置至它的原始状态，然后，将 Connection 对象返回至连接池，当新的应用程序连接请求时，该连接池可用。 | 将连接返回至原始状态，并保持所有打开的语句，但关闭所有结果集 不推荐在此情况下调用此方法 |
| 以应用程序服务器实现的连接池 | 由连接池实现来定义 | 将连接返回至原始状态，并保持打开的语句，但关闭结果集 如果您正在使用带有连接的语句池的 JDBC 3.0 特性，则此功能可能是有用的。当应用程序调用 Connection.close() 方法时，在将对象返回至连接池之前，应用程序服务器连接池管理器可调用入池的连接对象的scrubConnection()。 |
当调用 scrubConnection() 方法时，应用程序应正在使用仅限于服务器的连接。